<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Unit tests &mdash; Django 1.7.8.dev20150401230226 documentation</title>
    
    <link rel="stylesheet" href="../../../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../../',
        VERSION:     '1.7.8.dev20150401230226',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../../_static/doctools.js"></script>
    <link rel="top" title="Django 1.7.8.dev20150401230226 documentation" href="../../../index.html" />
    <link rel="up" title="Writing code" href="index.html" />
    <link rel="next" title="Submitting patches" href="submitting-patches.html" />
    <link rel="prev" title="Coding style" href="coding-style.html" />



 
<script type="text/javascript" src="../../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../../../ref/templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);
</script>


  </head>
  <body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../../../index.html">Django 1.7.8.dev20150401230226 documentation</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../../../index.html">Home</a>  |
        <a title="Table of contents" href="../../../contents.html">Table of contents</a>  |
        <a title="Global index" href="../../../genindex.html">Index</a>  |
        <a title="Module index" href="../../../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="coding-style.html" title="Coding style">previous</a>
     |
    <a href="../../index.html" title="Django internals" accesskey="U">up</a>
   |
    <a href="submitting-patches.html" title="Submitting patches">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="internals-contributing-writing-code-unit-tests">
            
  <div class="section" id="s-unit-tests">
<span id="unit-tests"></span><h1>Unit tests<a class="headerlink" href="#unit-tests" title="Permalink to this headline">¶</a></h1>
<p>Django comes with a test suite of its own, in the <tt class="docutils literal"><span class="pre">tests</span></tt> directory of the
code base. It&#8217;s our policy to make sure all tests pass at all times.</p>
<p>The tests cover:</p>
<ul class="simple">
<li>Models, the database API and everything else in core Django core (<tt class="docutils literal"><span class="pre">tests/</span></tt>),</li>
<li><a class="reference internal" href="#contrib-apps"><em>Contrib apps</em></a> (<tt class="docutils literal"><span class="pre">django/contrib/&lt;app&gt;/tests</span></tt> or <tt class="docutils literal"><span class="pre">tests/&lt;app&gt;_...</span></tt>).</li>
</ul>
<p>We appreciate any and all contributions to the test suite!</p>
<p>The Django tests all use the testing infrastructure that ships with Django for
testing applications. See <a class="reference internal" href="../../../topics/testing/overview.html"><em>Writing and running tests</em></a> for an explanation of
how to write new tests.</p>
<div class="section" id="s-running-the-unit-tests">
<span id="s-running-unit-tests"></span><span id="running-the-unit-tests"></span><span id="running-unit-tests"></span><h2>Running the unit tests<a class="headerlink" href="#running-the-unit-tests" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-quickstart">
<span id="quickstart"></span><h3>Quickstart<a class="headerlink" href="#quickstart" title="Permalink to this headline">¶</a></h3>
<p>Running the tests requires a Django settings module that defines the
databases to use. To make it easy to get started, Django provides and uses a
sample settings module that uses the SQLite database. To run the tests:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>git clone https://github.com/django/django.git django-repo
<span class="nv">$ </span><span class="nb">cd </span>django-repo/tests
<span class="nv">$ PYTHONPATH</span><span class="o">=</span>..:<span class="nv">$PYTHONPATH</span> ./runtests.py
</pre></div>
</div>
<div class="versionchanged">
<span class="title">Changed in Django 1.7:</span> <p>Older versions of Django required specifying a settings file:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ PYTHONPATH</span><span class="o">=</span>..:<span class="nv">$PYTHONPATH</span> python ./runtests.py --settings<span class="o">=</span>test_sqlite
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">runtests.py</span></tt> now uses <tt class="docutils literal"><span class="pre">test_sqlite</span></tt> by default if settings aren&#8217;t
provided through either <tt class="docutils literal"><span class="pre">--settings</span></tt> or <span class="target" id="index-0"></span><a class="reference internal" href="../../../topics/settings.html#envvar-DJANGO_SETTINGS_MODULE"><tt class="xref std std-envvar docutils literal"><span class="pre">DJANGO_SETTINGS_MODULE</span></tt></a>.</p>
</div>
<p>You can avoid typing the <tt class="docutils literal"><span class="pre">PYTHONPATH</span></tt> bit each time by adding your Django
checkout to your <tt class="docutils literal"><span class="pre">PYTHONPATH</span></tt> or by installing the source checkout using pip.
See <a class="reference internal" href="../../../topics/install.html#installing-development-version"><em>Installing the development version</em></a>.</p>
<p>Having problems? See <a class="reference internal" href="#troubleshooting-unit-tests"><em>Troubleshooting</em></a> for some common issues.</p>
</div>
<div class="section" id="s-using-another-settings-module">
<span id="s-running-unit-tests-settings"></span><span id="using-another-settings-module"></span><span id="running-unit-tests-settings"></span><h3>Using another <tt class="docutils literal"><span class="pre">settings</span></tt> module<a class="headerlink" href="#using-another-settings-module" title="Permalink to this headline">¶</a></h3>
<p>The included settings module allows you to run the test suite using
SQLite. If you want to test behavior using a different database (and
if you&#8217;re proposing patches for Django, it&#8217;s a good idea to test
across databases), you may need to define your own settings file.</p>
<p>To run the tests with different settings, ensure that the module is on your
<tt class="docutils literal"><span class="pre">PYTHONPATH</span></tt> and pass the module with <tt class="docutils literal"><span class="pre">--settings</span></tt>.</p>
<p>The <a class="reference internal" href="../../../ref/settings.html#std:setting-DATABASES"><tt class="xref std std-setting docutils literal"><span class="pre">DATABASES</span></tt></a> setting in any test settings module needs to define
two databases:</p>
<ul class="simple">
<li>A <tt class="docutils literal"><span class="pre">default</span></tt> database. This database should use the backend that
you want to use for primary testing</li>
<li>A database with the alias <tt class="docutils literal"><span class="pre">other</span></tt>. The <tt class="docutils literal"><span class="pre">other</span></tt> database is used to
establish that queries can be directed to different databases. As a result,
this database can use any backend you want. It doesn&#8217;t need to use the same
backend as the <tt class="docutils literal"><span class="pre">default</span></tt> database (although it can use the same backend if
you want to). It cannot be the same database as the <tt class="docutils literal"><span class="pre">default</span></tt>.</li>
</ul>
<p>If you&#8217;re using a backend that isn&#8217;t SQLite, you will need to provide other
details for each database:</p>
<ul class="simple">
<li>The <a class="reference internal" href="../../../ref/settings.html#std:setting-USER"><tt class="xref std std-setting docutils literal"><span class="pre">USER</span></tt></a> option needs to specify an existing user account
for the database. That user needs permission to execute <tt class="docutils literal"><span class="pre">CREATE</span> <span class="pre">DATABASE</span></tt>
so that the test database can be created.</li>
<li>The <a class="reference internal" href="../../../ref/settings.html#std:setting-PASSWORD"><tt class="xref std std-setting docutils literal"><span class="pre">PASSWORD</span></tt></a> option needs to provide the password for
the <a class="reference internal" href="../../../ref/settings.html#std:setting-USER"><tt class="xref std std-setting docutils literal"><span class="pre">USER</span></tt></a> that has been specified.</li>
</ul>
<p>Test databases get their names by prepending <tt class="docutils literal"><span class="pre">test_</span></tt> to the value of the
<a class="reference internal" href="../../../ref/settings.html#std:setting-NAME"><tt class="xref std std-setting docutils literal"><span class="pre">NAME</span></tt></a> settings for the databases defined in <a class="reference internal" href="../../../ref/settings.html#std:setting-DATABASES"><tt class="xref std std-setting docutils literal"><span class="pre">DATABASES</span></tt></a>.
These test databases are deleted when the tests are finished.</p>
<div class="versionchanged">
<span class="title">Changed in Django 1.7:</span> <p>Before Django 1.7, the <a class="reference internal" href="../../../ref/settings.html#std:setting-NAME"><tt class="xref std std-setting docutils literal"><span class="pre">NAME</span></tt></a> setting was mandatory and had to
be the name of an existing database to which the given user had permission
to connect.</p>
</div>
<p>You will also need to ensure that your database uses UTF-8 as the default
character set. If your database server doesn&#8217;t use UTF-8 as a default charset,
you will need to include a value for <a class="reference internal" href="../../../ref/settings.html#std:setting-TEST_CHARSET"><tt class="xref std std-setting docutils literal"><span class="pre">TEST_CHARSET</span></tt></a> in the settings
dictionary for the applicable database.</p>
</div>
<div class="section" id="s-running-only-some-of-the-tests">
<span id="running-only-some-of-the-tests"></span><h3>Running only some of the tests<a class="headerlink" href="#running-only-some-of-the-tests" title="Permalink to this headline">¶</a></h3>
<p>Django&#8217;s entire test suite takes a while to run, and running every single test
could be redundant if, say, you just added a test to Django that you want to
run quickly without running everything else. You can run a subset of the unit
tests by appending the names of the test modules to <tt class="docutils literal"><span class="pre">runtests.py</span></tt> on the
command line.</p>
<p>For example, if you&#8217;d like to run tests only for generic relations and
internationalization, type:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>./runtests.py --settings<span class="o">=</span>path.to.settings generic_relations i18n
</pre></div>
</div>
<p>How do you find out the names of individual tests? Look in <tt class="docutils literal"><span class="pre">tests/</span></tt> — each
directory name there is the name of a test. Contrib app names are also valid
test names.</p>
<p>If you just want to run a particular class of tests, you can specify a list of
paths to individual test classes. For example, to run the <tt class="docutils literal"><span class="pre">TranslationTests</span></tt>
of the <tt class="docutils literal"><span class="pre">i18n</span></tt> module, type:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>./runtests.py --settings<span class="o">=</span>path.to.settings i18n.tests.TranslationTests
</pre></div>
</div>
<p>Going beyond that, you can specify an individual test method like this:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>./runtests.py --settings<span class="o">=</span>path.to.settings i18n.tests.TranslationTests.test_lazy_objects
</pre></div>
</div>
</div>
<div class="section" id="s-running-the-selenium-tests">
<span id="running-the-selenium-tests"></span><h3>Running the Selenium tests<a class="headerlink" href="#running-the-selenium-tests" title="Permalink to this headline">¶</a></h3>
<p>Some admin tests require Selenium 2, Firefox and Python &gt;= 2.6 to work via a
real Web browser. To allow those tests to run and not be skipped, you must
install the <a class="reference external" href="https://pypi.python.org/pypi/selenium">selenium</a> package (version &gt; 2.13) into your Python path and run
the tests with the <tt class="docutils literal"><span class="pre">--selenium</span></tt> option:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>./runtests.py --settings<span class="o">=</span>test_sqlite --selenium admin_inlines
</pre></div>
</div>
</div>
<div class="section" id="s-running-all-the-tests">
<span id="s-running-unit-tests-dependencies"></span><span id="running-all-the-tests"></span><span id="running-unit-tests-dependencies"></span><h3>Running all the tests<a class="headerlink" href="#running-all-the-tests" title="Permalink to this headline">¶</a></h3>
<p>If you want to run the full suite of tests, you&#8217;ll need to install a number of
dependencies:</p>
<ul class="simple">
<li><a class="reference external" href="https://pypi.python.org/pypi/bcrypt">bcrypt</a></li>
<li><a class="reference external" href="https://pypi.python.org/pypi/docutils">docutils</a></li>
<li><a class="reference external" href="https://pypi.python.org/pypi/numpy">numpy</a></li>
<li><a class="reference external" href="https://pypi.python.org/pypi/Pillow/">Pillow</a></li>
<li><a class="reference external" href="http://pyyaml.org/wiki/PyYAML">PyYAML</a></li>
<li><a class="reference external" href="https://pypi.python.org/pypi/pytz/">pytz</a></li>
<li><a class="reference external" href="https://pypi.python.org/pypi/setuptools/">setuptools</a></li>
<li><a class="reference external" href="http://memcached.org/">memcached</a>, plus a <a class="reference internal" href="../../../topics/cache.html#memcached"><em>supported Python binding</em></a></li>
<li><a class="reference external" href="http://www.gnu.org/software/gettext/manual/gettext.html">gettext</a> (<a class="reference internal" href="../../../topics/i18n/translation.html#gettext-on-windows"><em>gettext on Windows</em></a>)</li>
<li><a class="reference external" href="https://pypi.python.org/pypi/selenium">selenium</a></li>
<li><a class="reference external" href="https://pypi.python.org/pypi/sqlparse">sqlparse</a></li>
</ul>
<p>You can find these dependencies in <a class="reference external" href="http://www.pip-installer.org/en/latest/user_guide.html#requirements-files">pip requirements files</a> inside the
<tt class="docutils literal"><span class="pre">tests/requirements</span></tt> directory of the Django source tree and install them
like so:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>pip install -r tests/requirements/py2.txt  <span class="c"># Python 3: py3.txt</span>
</pre></div>
</div>
<p>You can also install the database adapter(s) of your choice using
<tt class="docutils literal"><span class="pre">oracle.txt</span></tt>, <tt class="docutils literal"><span class="pre">mysql.txt</span></tt>, or <tt class="docutils literal"><span class="pre">postgres.txt</span></tt>.</p>
<p>If you want to test the memcached cache backend, you&#8217;ll also need to define
a <a class="reference internal" href="../../../ref/settings.html#std:setting-CACHES"><tt class="xref std std-setting docutils literal"><span class="pre">CACHES</span></tt></a> setting that points at your memcached instance.</p>
<p>To run the GeoDjango tests, you will need to <a class="reference internal" href="../../../ref/contrib/gis/install/index.html"><em>setup a spatial database
and install the Geospatial libraries</em></a>.</p>
<p>Each of these dependencies is optional. If you&#8217;re missing any of them, the
associated tests will be skipped.</p>
</div>
<div class="section" id="s-code-coverage">
<span id="code-coverage"></span><h3>Code coverage<a class="headerlink" href="#code-coverage" title="Permalink to this headline">¶</a></h3>
<p>Contributors are encouraged to run coverage on the test suite to identify areas
that need additional tests. The coverage tool installation and use is described
in <a class="reference internal" href="../../../topics/testing/advanced.html#topics-testing-code-coverage"><em>testing code coverage</em></a>.</p>
<p>To run coverage on the Django test suite using the standard test settings:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>coverage run ./runtests.py --settings<span class="o">=</span>test_sqlite
</pre></div>
</div>
<p>After running coverage, generate the html report by running:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>coverage html
</pre></div>
</div>
<p>When running coverage for the Django tests, the included <tt class="docutils literal"><span class="pre">.coveragerc</span></tt>
settings file  defines <tt class="docutils literal"><span class="pre">coverage_html</span></tt> as the output directory for the report
and also excludes several directories not relevant to the results
(test code or external code included in Django).</p>
</div>
</div>
<div class="section" id="s-contrib-apps">
<span id="s-id1"></span><span id="contrib-apps"></span><span id="id1"></span><h2>Contrib apps<a class="headerlink" href="#contrib-apps" title="Permalink to this headline">¶</a></h2>
<p>Tests for contrib apps go in their respective directories under
<tt class="docutils literal"><span class="pre">django/contrib</span></tt>, in a <tt class="docutils literal"><span class="pre">tests.py</span></tt> file. You can split the tests over
multiple modules by using a <tt class="docutils literal"><span class="pre">tests</span></tt> directory in the normal Python way.</p>
<p>If you have URLs that need to be mapped, put them in <tt class="docutils literal"><span class="pre">tests/urls.py</span></tt>.</p>
<p>To run tests for just one contrib app (e.g. <tt class="docutils literal"><span class="pre">auth</span></tt>), use the same
method as above:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>./runtests.py --settings<span class="o">=</span>settings django.contrib.auth
</pre></div>
</div>
</div>
<div class="section" id="s-troubleshooting">
<span id="s-troubleshooting-unit-tests"></span><span id="troubleshooting"></span><span id="troubleshooting-unit-tests"></span><h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-many-test-failures-with-unicodeencodeerror">
<span id="many-test-failures-with-unicodeencodeerror"></span><h3>Many test failures with <tt class="docutils literal"><span class="pre">UnicodeEncodeError</span></tt>.<a class="headerlink" href="#many-test-failures-with-unicodeencodeerror" title="Permalink to this headline">¶</a></h3>
<p>If the <tt class="docutils literal"><span class="pre">locales</span></tt> package is not installed, some tests will fail with a
<tt class="docutils literal"><span class="pre">UnicodeEncodeError</span></tt>.</p>
<p>You can resolve this on Debian-based systems, for example, by running:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>apt-get install locales
<span class="nv">$ </span>dpkg-reconfigure locales
</pre></div>
</div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../../../contents.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Unit tests</a><ul>
<li><a class="reference internal" href="#running-the-unit-tests">Running the unit tests</a><ul>
<li><a class="reference internal" href="#quickstart">Quickstart</a></li>
<li><a class="reference internal" href="#using-another-settings-module">Using another <tt class="docutils literal"><span class="pre">settings</span></tt> module</a></li>
<li><a class="reference internal" href="#running-only-some-of-the-tests">Running only some of the tests</a></li>
<li><a class="reference internal" href="#running-the-selenium-tests">Running the Selenium tests</a></li>
<li><a class="reference internal" href="#running-all-the-tests">Running all the tests</a></li>
<li><a class="reference internal" href="#code-coverage">Code coverage</a></li>
</ul>
</li>
<li><a class="reference internal" href="#contrib-apps">Contrib apps</a></li>
<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a><ul>
<li><a class="reference internal" href="#many-test-failures-with-unicodeencodeerror">Many test failures with <tt class="docutils literal"><span class="pre">UnicodeEncodeError</span></tt>.</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h3>Browse</h3>
  <ul>
    
      <li>Prev: <a href="coding-style.html">Coding style</a></li>
    
    
      <li>Next: <a href="submitting-patches.html">Submitting patches</a></li>
    
  </ul>
  <h3>You are here:</h3>
  <ul>
      <li>
        <a href="../../../index.html">Django 1.7.8.dev20150401230226 documentation</a>
        
          <ul><li><a href="../../index.html">Django internals</a>
        
          <ul><li><a href="../index.html">Contributing to Django</a>
        
          <ul><li><a href="index.html">Writing code</a>
        
        <ul><li>Unit tests</li></ul>
        </li></ul></li></ul></li></ul>
      </li>
  </ul>

  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="../../../_sources/internals/contributing/writing-code/unit-tests.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="../../../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">Apr 02, 2015</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="coding-style.html" title="Coding style">previous</a>
     |
    <a href="../../index.html" title="Django internals" accesskey="U">up</a>
   |
    <a href="submitting-patches.html" title="Submitting patches">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>